Image Replicator

The Image Replicator tool is a USB disk image that boots from a target device to capture or write USB drive-resident media directly onto the target without a host workstation. It runs from a USB drive and allows:

• Capturing an image of the device storage (eMMC/microSD)
• Writing an existing image back to media
• Creating bootable media for mass deployment

The USB disk image is based on Buildroot and contains a set of scripts that handle the capture and write processes. The processes and scripts are flexible, can be used as-is, or adapted into larger production processes to format and load data onto devices. A single USB drive can be used to capture images from a device and then, once inserted in to other devices, write those same images onto other devices. The capture process is not necessary if it is not needed. Images for the target device can be copied to the USB drive, booted on compatible units, and have the target images written to that unit's media.

Image Capture Process​

The image capture process performs the following steps. For more detailed information, see the Image Capture section below.

1. If no valid images exist on the disk, image capture starts.
2. For each valid media present on the unit, a bit for bit copy of the source is made.
3. This image is mounted, sanitized (to remove unneeded files and allow safe copying of the image to other units), and saved as either a disk image or a tarball, depending on the partition layout of the source disk.
4. All images and tarballs are compressed, with both the output files' MD5 hash saved, as well as all of the files contained in the root partition (MD5 hashes saved) to a file for later verification.

The captured images and tarballs are named such that the USB Image Replicator disk can be immediately used to boot another unit and have it perform the Image Write process, writing that unit's media with the captured images.

Image Write Process​

The image write process performs the following steps. For more detailed information see the Image Write section below.

1. For each valid media present on the unit, find the first valid source image file for it.
2. If a source image exists for a media that is not present on the unit, then the process indicates a failure.
3. If the source image is a tarball, format the target disk with an appropriate file system and unpack it to the target disk, verifying all files against the MD5 hash file list after they are written.
4. If the source image is a disk image, write that to the target disk. If an MD5 file for the disk image exists, read back the written disk and compare it to the hash.

Creating a USB Image Replicator Disk​

Image Replicator USB disk images can be found below:

Disk image: tsimx6ul-usb-image-replicator.dd.xz

Tarball: tsimx6ul-usb-image-replicator-rootfs.tar.xz

Two types of USB Image Replicator images are available for this platform: a tarball and an actual disk image. They both have the same contents yet provide different methods to write the Image Replicator tool to a USB disk.

• Disk Image (.dd.xz)

  • The disk image is easier to write from different workstation OSes, will auto-expand to the full disk length on its first boot, and is intended to be used for image capture (and later image writing) due to its small size and auto-expansion process. We recommend this route for users who may not have access to a Linux workstation or need to capture images from a golden unit first.

• Tarball Image (.tar.xz)

  • The tarball image is easiest to write from a Linux workstation, but requires creating a partition table on the USB disk (if one does not already exist), formatting the filesystem, and unpacking the tarball. It can readily be used for both image capture and writing, but is easiest when image capture is not needed, due to the auto-expansion process.

Disk Image​

This process uses a small disk image that can be written to a USB device. This disk image uses an ext3 filesystem which expands on its first boot to the full length of the disk before beginning the image capture process, and is recommended for users who may not have access to a Linux workstation or who need to capture images from a golden unit.

It is possible to use the disk image only for image writing. However, to ensure that full disk space is available, it is recommended to write the disk image to a USB drive, set the IR_NO_CAPTURE_* Image Replicator Runtime Options, boot it on the target unit, let the system boot and expand to the disk, insert the USB drive back in to a workstation, and then copy in the desired image files for the target unit from the workstation.

Writing Disk Image From a Linux Workstation​

The disk image can be written via the command line with the dd command (replace /dev/sdX with the correct USB device node):

xzcat <platform>-usb-image-replicator.dd.xz > /dev/sdX

Graphical tools also exist for this purpose, for example balenaEtcher[1] offers this functionality.

Writing Disk Image From a Windows Workstation​

A number of tools exist for writing an image to a USB drive, including (but not limited to) balenaEtcher[1] and Win32DiskImager[2]

Writing Disk Image From a MacOS Workstation​

We recommend using a tool such as balenaEtcher[1] to write disk images.

• [1] embeddedTS is not affiliated with this tool. balenaEtcher version 1.5.101 tested in Windows 10 on 20220216
• [2] embeddedTS is not affiliated with this tool. Win32DiskImager 1.0.0 tested in Windows 10 on 20220216. Cannot handle compressed images, must first decompress disk image.

Tarball​

This process is easiest on a Linux workstation, but can be performed on other operating systems so long as they can support a compatible filesystem, the xz compression algorithm, as well as the tarball archive format. Note that in many cases, one of our computing platforms running our stock Linux image can be used if a Linux workstation is not available. After writing the tarball to a USB disk, the full length of the USB disk would be available to copy source images, to write them to other units.

The image replicator and scripts require a minimum of 50 MB. Additionally, the size of target disk images or tarballs used also dictate the minimum USB disk size required. The USB drive should have only a single partition, which is formatted ext2[1] / 3 / 4[2] or FAT32/vfat[3]

Writing Tarball From a Linux Workstation​

# This assumes USB drive is /dev/sdc:
sudo mkfs.ext3 /dev/sdc1
sudo mkdir /mnt/usb/
sudo mount /dev/sdc1 /mnt/usb/
sudo tar --numeric-owner -xf /path/to/<platform>-usb-image-replicator-rootfs.tar.xz -C /mnt/usb/
sudo umount /mnt/usb/

Writing Tarball From a Windows Workstation​

A third party tool is recommended, as native Windows archive tools have occasionally not worked correctly. Tools such as 7-Zip[4] or PeaZip[5] are known working. (It may also be possible to use Windows Subsystem for Linux following the Linux Workstation instructions above, but this has not been tested.)

Note that some Windows tools may attempt to use the whole disk, rather than create a partition table. A partition table with a single partition is required for U-Boot support.

With a formatted USB disk, the archive can be unpacked to the root folder of the USB disk. Be sure to not unpack the tarball contents into a new folder on the drive, as this will not boot.

• [1] The ext2 filesystem has a max file size limit as low at 16 GiB. This may cause issues for Image Capture.
• [2] Use of ext4 may require additional options. U-Boot on some platforms does not support the 64-bit addressing (added as default) in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options -O ^64bit,^metadata_csum may need to be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed, nor are they needed for ext2 / 3.
• [3] The FAT32 (supported by vfat in Linux) filesystem has a max file size limit of 4 GiB. This may cause issues for Image Capture.
• [4] embeddedTS is not affiliated with this tool. 7-Zip 21.07 tested in Windows 10 on 20220222
• [5] embeddedTS is not affiliated with this tool. PeaZip 7.2.0 tested in Windows 10 on 20220222

Running the Image Replicator Tool​

Once a USB drive is formatted with the Image Replicator tool (see Creating a USB Image Replicator Disk for the correct files and process), boot to this USB drive (note that the Image Replicator already sets up the correct U-Boot boot scripts to boot to the USB drive, see the aforementioned section for details on how to make U-Boot call the scripts on the USB drive). This will start either image capture if no disk images/tarballs are present on the USB drive, or image write if there are disk images/tarballs present on the USB drive.

Image Replicator Runtime Options​

Some of the runtime operations of the Image Replicator can be specified. These are handled by creating empty files in the root folder of the bootable USB drive. When booted, these files are analyzed and actions taken based on them.

Image Replicator LED Status​

The green and red LEDs of the platform are used to indicate status.

Any LED patterns not matching the table below indicate different operational states of the platform itself, e.g. executing the bootloader, the kernel is running but Image Replicator has not yet started, etc.

Image Capture​

If no valid images to write exist on the booted USB Image Replicator drive, the image capture process starts automatically.

Note that while in progress, the USB Image Replicator drive is mounted read-write. Do not remove power or disconnect the USB Image Replicator drive until the whole process has completed.

To help diagnose failures, files in /tmp/logs/ contain output from each capture process.

For each media present on the unit (SD / eMMC / SATA / etc.), the image capture process will do the following:

1. Copy the entire media image to an appropriately named file on the USB Image Replicator drive, e.g. sdimage.dd. No data is written to the source media and it is never mounted. The source disk can follow the stock partition layout, or implement a customized one.
2. Perform an fsck on the Linux rootfs partition in the image file. Note that, if deviating from the standard partition layout, it may be necessary to modify the scripts handling the capture process.
3. Mount the Linux rootfs partition from the image file and sanitize the filesystem. The sanitization process removes temporary files (e.g. /log/ files), unique files (e.g. ssh private key files, machine ID files), adds a file to indicate that it is a custom image with the date as its contents, etc. The full list of operations can be found in this script. It may be necessary to modify this file for unique situations.
4. If the media's partition layout uses only a single partition, the filesystem is packed in to a tarball on the USB Image Replicator drive which is appropriately named and compressed, e.g. sdimage.tar.xz. The image file is then unmounted and removed from the USB Image Replicator drive.
5. If the media's partition layout uses multiple partitions, the image file is then unmounted, an md5sum of the image file taken, compressed and appropriately named on the USB Image Replicator drive, e.g. emmcimage.dd.xz, and then an md5sum of the compressed image is taken.

Note that when using this process, the USB Image Replicator drive that is used must be sized large enough to handle multiple compressed images as well as the uncompressed copy of the media image actively being worked with. If the image capture process runs out of space, the process will indicate a failure via the LEDs.

The images files captured are saved to the root folder of the USB Image Replicator drive. Upon completion, it is safe to remove power or unplug the USB drive.

For more details on the image capture process, see this script.

Image Write​

This process is used to write existing images to media on a target unit. If appropriately named disk images or tarballs (see table below) are present in the root folder of the USB Image Replicator drive when booted, then the startup scripts will start the image writing process. The latest disk images we provide for our platforms can be downloaded from our FTP site, see the backup and restore section for links to these files.

Note that the USB Image Replicator drive remains read-only through the entire process but target devices may be mounted or actively written. It is not advised to remove power or disconnect the USB Image Replicator drive until the whole process has completed.

To help diagnose failures, files in /tmp/logs/ contain output from each writing process.

The Image Replicator script expects disk images or tarballs to have specific names to match the target media. The script will attempt to match tarball and then disk image names (in the order they are listed in the table below) for each target media, using the first file that is found to write to the target media. Note that symlinks can be used on the USB Image Replicator disk if formatted with a filesystem that supports symlinks. This can be used, for example, to write the same tarball to both SD and eMMC from only a single copy of the source tarball.

Upon completion, it is safe to remove power or unplug the USB drive.

For more details on the image write process, see this script.

The following table is the list of valid file names and how they are processed:

Building the Image Replicator from Source​

The Image Replicator tool uses Buildroot to create the bootable USB disk image and tarball. See the project repository on github for information on compatibility and instructions on building: https://github.com/embeddedTS/buildroot-ts

Creating a Production Image​

It is usually desired to create a golden image to use for unit production after development is complete. This process can vary greatly from application to application but there are a few steps that are going to be most often wanted. These include cleaning up temporary files, removing files that should be unique and re-generated on the first boot (SSH keys, machine-id files, etc.), setting up the hostname, and so on. We have created a script that will automate most of this process and provides hooks for additional scripts to be called as well. The script is simply passed the device node of the development disk or an existing .dd file. From this, it will create a new .dd file based on the partition scheme with all modifications made to the new image. The image source is left completely untouched and is read only. The script also assumes that the last partition on the disk is the bootable linux partition. If this is not the case or there are multiple partitions that are used in the end application, the script will need to be modified in order to accommodate this fact.

The simplest use of the script is:

./prep_customer_image /dev/sdX <output base name>

Note that /dev/sdXv will need to be changed accordingly. Be sure to pass the whole disk and not just a partition.

The <output base name> is used as the base for all files output. For example, if "TechnologicSystems-latest" was used, then the compressed tarball output would be named "TechnologicSystems-latest.tar.bz2" (or it may end with ".tar.xz" depending on the compression used by the script). If no base name is provided, then the current date is used.

Additionally, there are two hooks available in the 'prep_customer_image' script, "prep" and "post". The top of the file has two variables, PREP_SCRIPTS="" and POST_SCRIPTS="". Adding in a space separated list of script names to those variables will cause them to be called in order. For example, setting PREP_SCRIPTS="add_application change_hostname" will cause the 'prep_customer_image' script to run through its initial steps, then call ./add_application, then call ./change_hostname, and then will continue with the rest of the script steps.

Every script for "prep" and "post" is called with a single argument, the name of the image file. This specifically will be <output base name>.dd. At the time of calling the prep scripts, the folder ./mount_point/ will have the last partition of the image file mounted as read/write. It is not wise to modify the image file directly since it is already mounted. All of the post scripts are called after the last partition of the image file is unmounted. This can be useful for creating additional file outputs, extracting specific partition images, etc., from the image itself. We have used these hooks in the past to remove special files and create additional images for our DoubleStore based devices.

It is also possible to run this script directly on the device when booted. This can be used to take an image of eMMC for example, when booted from the SD card. We always recommend doing initial development on SD, creating an image from that on a host PC, and then transferring it to the eMMC. This process makes development and image creation faster. If using the 'prep_customer_image' script from a booted device, be sure there is enough free space as the script creates a disk image of the target disk and then copies that in to a tarball, compressing everything as the final step.

microSD Card​

Most SD cards ship with a single partition, which is ideal. However the instructions below will destroy the partition table and use 'parted' to recreate it and make a single partition. Note that any other preferred tool can be used instead, however the partition table must be "MBR" format for U-Boot to properly parse it.

Using other OSs​

At this time, we're unable to provide assistance with writing SD cards for our products from non-Linux based operating systems. We acknowledge however, that there are methods to write images and files from a variety of difference operating systems. If a native installation of Linux is unavailable, we recommend using a Virtual Machine. See the Getting Started section for links to common virtualization software and Linux installation.

Using a Linux workstation​

An SD card can be written to allow it to be bootable. Download the above file and write this from a Linux workstation using the information below. A USB SD adapter can be used to access the card; or if the workstation supports direct connection of SD cards, that can be used instead. Once inserted in to the workstation, it is necessary to discover which /dev/ device corresponds with the inserted SD card before the image can be written.

Option 1: using lsblk​

Newer distributions include a utility called lsblk which allows simple identification of the intended card.

Note: This command may need to be run as the root user:

$ lsblk
NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sdY      8:0    0   400G  0 disk 
├─sdY1   8:1    0   398G  0 part /
├─sdY2   8:2    0     1K  0 part 
└─sdY5   8:5    0     2G  0 part [SWAP]
sr0     11:0    1  1024M  0 rom  
sdX      8:32   1   3.9G  0 disk 
├─sdX1   8:33   1   7.9M  0 part 
├─sdX2   8:34   1     2M  0 part 
├─sdX3   8:35   1     2M  0 part 
└─sdX4   8:36   1   3.8G  0 part

In this case the, SD card is 4GB, so sdX is the target device and already contains 4 partitions. Note that sdX is not a real device, it could be sda, sdb, mmcblk0, etc. embeddedTS is not responsible for any damages cause by using the improper device node for imaging an SD card. The instructions below to write to the device will destroy the partition table and any existing data!

Option 2: Using dmesg​

After plugging in the device, the dmesg command can be used to list recent kernel events. When inserting a USB adapter, the last few lines of dmesg output will be similar to the following (note that this command may need to be run as the root user):

$ dmesg
...
scsi 54:0:0:0: Direct-Access     Generic  Storage Device   0.00 PQ: 0 ANSI: 2
sd 54:0:0:0: Attached scsi generic sg2 type 0
sd 54:0:0:0: [sdX] 3862528 512-byte logical blocks: (3.97 GB/3.84 GiB)
...

In this case, sdX is shown as a 3.97GB card with a single partition. Note that sdX is not a real device, it could be sda, sdb, mmcblk0, etc. embeddedTS is not responsible for any damages cause by using the improper device node for imaging an SD card. The instructions below to write to the device will destroy the partition table and any existing data!

The instructions below use the latest stock image, but it is also possible to use this process to update the board to the Linux 4.9 kernel with Debian Stretch image.

The following commands will reformat the first partition of the SD card, and unpack the latest filesystem on there. Replace the /dev/sdX on the first line with the correct whole disk device node!

# Update this variable to match the specific device node as it appears on your PC!
export SD_DEV="/dev/sdX"

# Verify nothing else has this mounted
sudo umount "${SD_DEV}"1

# Remove, and re-set the partition table, ensuring there is a single partition. Additional partitions can be added, however U-Boot expects the 1st partition to have the root filesystem tarball.
sudo dd if=/dev/zero bs=512 count=1 of="${SD_DEV}"
sudo parted -s -a optimal "${SD_DEV}" mklabel msdos
sudo parted -s -a optimal "${SD_DEV}" mkpart primary ext3 0% 100%
sudo mkfs.ext3 -F "${SD_DEV}"1

# Mount, unpack filesystem tarball, and flush all cached data
sudo mkfs.ext3 "${SD_DEV}"1
sudo mkdir /mnt/sd
sudo mount "${SD_DEV}"1 /mnt/sd/
wget https://files.embeddedTS.com/ts-arm-sbc/ts-7553-V2-linux/distributions/ts7553-V2-latest.tar.xz
sudo tar -xf ts7553-V2-latest.tar.xz -C /mnt/sd
sudo umount /mnt/sd
sync

Once written, the files on disk can be verified to ensure they are the same as the source files in the archive. Reinsert the disk to flush the block cache completely, then run the following commands (Note that this expects to have the bash variable still set up from above):

mount /dev/mmcblk1p1 /mnt/emmc
cd /mnt/emmc/
md5sum --quiet -c md5sums.txt
cd -
umount /mnt/emmc
sync

The md5sum command will report what differences there are, if any, and return if it passed or failed.

eMMC Storage​

U-Boot UMS (USB mass storage)​

U-Boot on the board supports the ums command to allow the eMMC device (or SD card, or USB device) to be accessible directly on a host PC via USB mass storage. This method is generally slower than direct access from Linux when booted from SD on board itself, but it allows for direct updating of the flash media from a host device.

On the board, set the U-Boot jumper before applying power. Insert the USB device cable to a host PC and open the serial console. At the U-Boot prompt, run the following command:

run emmc-ums

The USB serial will immediately disconnect, and the USB mass storage device provided by the board will begin to enumerate. The following commands can then be used to set up the eMMC and unpack the filesystem tarball on to it. The instructions below use a software image.

Note that the instructions use a bash variable to define the device node; this allows the commands to be copy/pasted as-is to a terminal or in a script. Ensure that the correct device node is passed! The node /dev/sdX is used in the example below, update that line to use the correct whole-device node.

# Update this variable to match the specific device node as it appears on your PC!
export UMS_DEV="/dev/sdX"

# Verify nothing else has the partition mounted
sudo umount "${UMS_DEV}"1

# Remove, and re-set the partition table, ensuring there is a single partition that ends just before the last sector of disk
sudo dd if=/dev/zero bs=512 count=1 of="${UMS_DEV}"
sudo echo 'label: dos' | sfdisk "${UMS_DEV}"
sudo parted -s -a optimal "${UMS_DEV}" mkpart primary ext3 0% 99%
sudo mkfs.ext3 -F "${UMS_DEV}"1

# Mount, unpack filesystem tarball, and flush all cached data
sudo mkdir /mnt/emmc
sudo mount "${UMS_DEV}"1 /mnt/emmc
wget https://files.embeddedTS.com/ts-arm-sbc/board-linux/distributions/ts7553-V2-latest.tar.xz
sudo tar -xf ts7553-V2-latest.tar.xz -C /mnt/emmc
sudo umount /mnt/emmc
sync

Once written, the files on disk can be verified to ensure they are the same as the source files in the archive. Reinsert the disk to flush the block cache completely, then run the following commands (Note that this expects to have the bash variable still set up from above):

mount /dev/mmcblk1p1 /mnt/emmc
cd /mnt/emmc/
md5sum --quiet -c md5sums.txt
cd -
umount /mnt/emmc
sync

The md5sum command will report what differences there are, if any, and return if it passed or failed.

At this point, the device is unmounted and is sync'ed. The board can safely be powered off. Be sure to disconnect the USB cable as well, to ensure the system is fully powered off.

Boot from SD​

These commands assume the board is booted from the SD card, the user is logged in as root, and eMMC already contains a single partition:

# Verify nothing else has the partition mounted
umount /dev/mmcblk1p1

mkfs.ext3 /dev/mmcblk1p1
mount /dev/mmcblk1p1 /mnt/emmc
wget https://files.embeddedTS.com/ts-arm-sbc/board-linux/distributions/ts7553-V2-latest.tar.xz
tar -xf ts7553-V2-latest.tar.xz -C /mnt/emmc
umount /mnt/emmc
sync

Once written, the files on disk can be verified to ensure they are the same as the source files in the archive. Reinsert the disk to flush the block cache completely, then run the following commands (Note that this expects to have the bash variable still set up from above):

mount /dev/mmcblk1p1 /mnt/emmc
cd /mnt/emmc/
md5sum --quiet -c md5sums.txt
cd -
umount /mnt/emmc
sync

The md5sum command will report what differences there are, if any, and return if it passed or failed.