Toradex Easy Installer

The Application runs completely in memory, hence the complete internal flash can be erased, (re)partitioned, formatted or written. The image to be flashed can be obtained over the Internet (via Ethernet), from a USB Flash Drive or an SD card.

Image Sources

Toradex provides ready-made images which can be downloaded directly using Toradex Easy Installer's Internet capabilities or as zip/tar files which can be extracted to a USB Flash Drive/SD Card.

Internet

The Toradex Easy Installer runs a DHCP client on the Ethernet port. As soon as the image gets an IP address assigned, the module will try to download a list of images from the Toradex image server (using HTTP). In case this fails (e.g. due to missing DNS server or standard Gateway) an error will be shown. Make sure that your DHCP provides a complete Network configuration which allows Internet access. To force a new DHCP request you can unplug and replug the Ethernet cable.

Local Media

The Toradex Easy Installer continuously monitors external devices. As soon as the Kernel detects a new device, the installer will try to mount all partitions and scan for images. The images will be detected by the description JSON file named image.json (see Image Format below). After scanning all directories the media will get unmounted so that users can safely unplugging the device after scanning. If the user unplugs the device, the images will disappear from the list of available images. Since only metadata are read at this time, it is required to keep the media plugged in in case an image from that media shall be installed.

Supported file systems are ext2/3/4, FAT and NTFS.

• USB Flash Drives: USB Flash Drive (USB mass storage device class) devices connected to the USB Host or OTG port
• SD Card: SD cards plugged in any standard SD card port are supported.

The Links to download Toradex Easy installer images are available in the Getting Started section (chapter Install Images).

Usage

By default, the Toradex Easy Installer displays on VGA, parallel RGB and HDMI/DVI-D (mirror mode) with a resolution of 640x480 (VGA display timings). Additionally, the UI can be accessed via VNC, either over Ethernet (IP address depends on your DHCP server) or via USB Device virtual Ethernet Link (RNDIS) on IP 192.168.11.1. The graphical user interface can be controlled by any USB keyboard/mouse or via VNC. If unattended installation is required an auto install mode is available too (see chapter Auto Installation).

• 

Install (i)

After selecting the image you wish to install the "Install" button starts the installation. If the image is obtained through a network, some metadata will get downloaded first (such as Release Notes, License text, prepare and wrap-up scripts). After accepting License and Release Notes, the block devices will be prepared (partitioned/formatted) as specified and the data to be written will be downloaded and unpacked in one step. Since this step is done in one step (multiple commands connected through pipes) the image size can exceed the modules main memory capacity.

• 

Note: In case any step during Installation fails, an error message will be shown and the option to go back to the main menu will be shown. At this point, it is likely that the Toradex Easy Installer is no longer stored on the internal flash (e.g. due to repartitioning). Hence it is recommended to retry flashing the same image or install the Toradex Easy Installer so another retry can be made later.

• 

At this point, all data are stored on internal flash and caches are flushed (synced). It is not required to click on any of this three buttons, it is perfectly fine to just reset or turn off the system.

Refresh (r)

This button will reload the image list obtained over the network.

Mass Storage (u)

This button allows exporting the internal flash as USB mass storage (eMMC based devices only). One can use this after flashing an image to transfer additional files manually or examine the data written to internal flash. Currently, this exports three disks: The eMMC main user partition (read/write) and the two eMMC boot partitions (read-only).

Note: This is only available if RNDIS has been disabled.

RNDIS (n)

RNDIS provides a USB Device virtual Ethernet Link (RNDIS). The USB RNDIS mode is enabled by default which allows users without a display to still use the Toradex Easy Installer. The module will run a DHCP server on the link so that the host computer connected to the module will receive an IP address automatically. The module has the IP on 192.168.11.1 assigned statically.

Depending on your Windows version it might be necessary to manually install the driver. Via Device Manager, right-click and select "Update Driver...", choose the "Microsoft Corporation" "Remote NDIS Compatible Device" driver.

Erase Flash (c)

Erase flash erases all modules internal flash using blkdiscard (eMMC only). The eMMC controller will be notified to discard data of all blocks, hence the complete device will appear as empty (all zeros).

Exit (Esc)

Reboots the module.

License

Shows the License information for the Qt-based UI. Note that there are external utilities part of the Toradex Easy Installer which are licensed under a different Licenses. Refer to the files stored under /usr/share/common-licenses/ and /usr/share/common-licenses/license.manifest for an overview.

Auto Installation

To automatically install an image, the image can be marked as "auto install" image using the autoinstall property in the image.json file. If that property is set to true the image will be flashed to the module automatically and unattended. This can be useful for production programming. Any image can carry the autoinstall property. If multiple images have the property set to true the outcome will depend on the order of how images get processed. There is no guaranteed order, so it is recommended to only use one local media with only one image having the autoinstall property set to true.

When flashing is finished, the same dialog as with regular flashing will be shown. This is useful for the operator to know that the image has been successfully installed. Note that although there are options to interact, there is no interaction needed: The operator can safely turn off the module at that point. If a reboot is required behavior is required, the wrapup_script can be extended with the reboot command:

 wrapup.sh
...
reboot -f
exit 0

Toradex Easy Installer Upgrade

If an image is not compatible with the current running Toradex Easy Installer (the config_format is higher than the supported format), then the image won't be considered for automatic installation. One can provide a new version of the Toradex Easy Installer alongside with the autoinstall property set to true too. If the currently running Toradex Easy Installers version is older than the provided installer (determined using the version and isinstaller property`), then the new Toradex Easy Installer will be installed first. This behavior allows to automatically upgrade the Toradex Easy Installer before installing the final image. It is useful if a newer installer is required to install the image.

• 

This screenshot shows this situation: The grayed out image requires a newer Toradex Easy Installer. Happily, there is a 0.4 version available. Both images can safely carry the autoinstall property since the Toradex Easy Installer only updates itself if the version is newer then the current version.

Speed improvements flashing Linux images

The main part of Linux images (the boots/rootfs files) is compressed using the LZMA2 algorithm (xz files). The format offers relatively high decompression speed and high compression ratio. However, if the image is read from a high bandwidth source the flashing process is limited by the decompression speed (CPU). The decompression utility xz does not offer multi-threaded decompression, hence it is limited to a single CPU. On a Cortex A7@1GHz (Colibri iMX7) the average decompression speed has been measured to be around 8.4MB/s.

Using xz is a good compromise if the image is downloaded over the Internet or otherwise relatively slow connection. Local media such as SD cards or USB flash drive offer much higher bandwidth. It is often faster to store the image uncompressed as a tar file in those cases. Measurements have shown up to 3 times faster flash times (e.g. 7s instead of 21s to extract/write a 130MB root file system). Currently, the OpenEmbedded image class does not offer to create uncompressed images. To convert a regular image to an uncompressed image, simply decompress the *.rootfs.tar.xz and *.boots.tar.xz files using xz -d and make sure the filename properties in the images descriptor file image.json points to the unpacked *.tar files.

Further speed improvements might be obtainable by using pre-built file system images and the raw file writing capabilities of Toradex Easy Installer. This method has not been evaluated by Toradex yet.

Unattended flashing over Ethernet

The Toradex Easy Installer can be used to flash images from a HTTP Webserver. Using a configuration file as described in the Configuration Format chapter in the Configuration Files tab the Toradex Easy Installer can read the images from a custom/local URL.

Note: Without a local media there is currently no way to provide the Installer a custom URL. There exists a work around documented further below.

Example configuration

The requirements on the PC side are:

• Linux PC (e.g. Ubuntu)
• dnsmasq (for DNS approach below)
• nginx
• Host side IP address 192.168.10.1 (can be changed)
• Tested with Toradex Easy Installer 1.4 (earlier versions may work as well)

Make sure you have a nginx configuration that looks as follows:

 /etc/nginx/sites-available/default
server {
   listen 80 default_server;
   listen [::]:80 default_server;
   root /var/www/html;
   index index.html index.htm index.nginx-debian.html;
   server_name _;
   location / {
       try_files $uri $uri/ =404;
   }
}

Make sure that /etc/nginx/sites-enabled/default links to the file /etc/nginx/sites-available/default:

sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/default

Now you can create a image list JSON file that looks as follows (example for Apalis TK1):

 /var/www/html/image_list.json
{ 
 "config_format": 1, 
 "images": [ 
   "apalis_tk1/image.json" 
 ] 
} 

Make a directory /var/www/html/apalis_tk1 to store your Tezi image along with all required files. Set the autoinstall flag to true:

 image.json
{
   "autoinstall": true,
...
}

Make sure that you restart nginx:

sudo systemctl restart nginx

Once the Toradex Easy Installer boots it should automatically flash the image provided on your web server. If you need log information, add them to prepare.sh and wrapup.sh. You can for example use the nc command for sending log files over Ethernet.

Custom Image Server without Local Media

The Toradex Easy Installer always tries to load an image_list.json from the hard coded URL http://tezi.toradex.com/image_list.json. Using a custom DNS server one can redirect tezi.toradex.com to a local production PC.

Redirecting DNS can be easily done using Dnsmasq. This example shows how to use Dnsmasq as a DHCP and DNS server to serve the module an IP address and provides a custom DNS server pointing tezi.toradex.com to the production PC as well:

 /etc/dnsmasq.conf
interface=<network interface>
dhcp-range=192.168.10.50,192.168.10.150,12h # Use different IPs if needed
address=/tezi.toradex.com/192.168.10.1 # Use IP address of your network interface

Make sure you restart Dnsmasq:

sudo systemctl restart dnsmasq

Once the Toradex Easy Installer boots it should connect using HTTP to the IP specified to download the image list and consequently install the image from the local webserver.

The Toradex Easy Installer makes use of JSON files. If required, the files can be edited using a plain text editor. However, care must be taken to not violate the JSON specification. To make sure the JSON file is still well formatted an online JSON validator can be useful (e.g. jsonlint.com).

Image Format

The image is described in a JSON image file. Toradex provides images with a proper JSON image file. However, depending on the use case you might need to alter the JSON image file e.g. to add an additional partition. The easiest way is to take an existing image.json file and alter it accordingly.

This chapter lists the available properties and how they get interpreted by the Toradex Easy Installer.

The JSON consists of a single root dictionary with several mandatory properties (*=Mandatory). An image can define its configuration format. Newer configurations support more features but require a newer Toradex Easy Installer version.

Block Devices

Each blockdev entry has a name and either a partitions or content node or both. In case using partition table and (raw) content, the Toradex Easy Installer will first create the partition table and then write the content according to the specification. Make sure that partition table created and data written do not conflict!

Partition

If partitions are specified, the installer will create an MBR/DOS-style partition table. Currently, only primary partitions are supported. All partition will be aligned to 4 megabyte boundaries (8192 blocks). A partition specification knows the following properties:

MTD Devices

Each blockdev entry has a name and either a content, ubivolumes or winceimage node.

UBI volume

WinCE image

The WinCE image section allows writing a WinCE image in the sparse file format to raw NAND (uses the utility flash-wince).

Common

Content

For block devices, content can either be raw data (dd-style) or a file system.

For MTD device, content can only be raw data (uses Linux nandwrite command).

For UBI volume, content can either be raw data (uses Linux ubiupdatevol command) or ubifs.

Raw Files

*=Mandatory property

Example

This is a typical example derived from a standard Linux image.json file: It creates the usual two partition layout, a FAT partition for the Kernel/Device Trees and a ext3 partition for the root file system. An additional third partition has been added to create a location for user data. The filename or filelist property can be used to pre-install user/application data.

{
    "config_format": 1, 
    "autoinstall": true, 
    "name": "Toradex Embedded Linux BSP using LXDE desktop", 
    "description": "Toradex Embedded Linux BSP using LXDE desktop.", 
    "version": "V2.6.1", 
    "release_date": "2016-10-13", 
    "prepare_script": "prepare.sh", 
    "wrapup_script": "wrapup.sh", 
    "marketing": "marketing.tar", 
    "icon": "toradexlinux.png", 
    "supported_product_ids": [
        "0027", 
        "0028", 
        "0029", 
        "0035"
    ], 
    "blockdevs": [
        {
            "name": "mmcblk0", 
            "partitions": [
                {
                    "partition_size_nominal": 16, 
                    "want_maximised": false,
                    "content": {
                        "uncompressed_size": 4, 
                        "filesystem_type": "FAT", 
                        "filename": "Apalis_iMX6_LinuxImage.bootfs.tar.xz", 
                        "mkfs_options": "", 
                        "label": "BOOT"
                    }
                }, 
                {
                    "partition_size_nominal": 512, 
                    "want_maximised": false,
                    "content": {
                        "uncompressed_size": 300, 
                        "filesystem_type": "ext3", 
                        "filename": "Apalis_iMX6_LinuxImage.rootfs.tar.xz", 
                        "mkfs_options": "", 
                        "label": "RFS"
                    }
                }, 
                {
                    "partition_size_nominal": 512, 
                    "want_maximised": true,
                    "content": {
                        "filesystem_type": "ext3",
                        "label": "DATA"
                    }
                }
            ]
        }, 
        {
            "name": "mmcblk0boot0"
            "content": {
                "filesystem_type": "raw",
                "rawfiles": [
                    {
                        "filename": "SPL",
                        "dd_options": "seek=2"
                    },
                    {
                        "filename": "u-boot.imx",
                        "dd_options": "seek=138"
                    }
                ]
            },
        }
    ]
}

Image List Format

Images loaded from an HTTP server need an index file which points to the individual images. The file name is typically image_list.json, but it can be anything. A local HTTP server needs such an image list file to point to the individual images.

This example points to two images, which are located in the directories Apalis_iMX6_LinuxImage_V2.6.2 and Apalis_iMX6_LinuxConsoleImage_V2.6.2 relative to the location of this index file:

{
  "config_format": 1,
  "images": [
    "Apalis_iMX6_LinuxImage_V2.6.2/image.json",
    "Apalis_iMX6_LinuxConsoleImage_V2.6.2/image.json"
  ]
}

Configuration Format

The Toradex Easy Installer configuration file allows adding additional HTTP image sources. The configuration file needs to be named tezi_config.json and located on the root of any partition on a supported external storage media (SD card or USB flash drive). This allows extending the search locations for image lists beyond the pre-configured Toradex servers, e.g. to distribute images in a local network or over RNDIS.

{
  "config_format": 1,
  "image_lists": [
     "http://192.168.10.2:8008/image_list.json"
  ]
}

Sometimes special boot parameters need to be passed to Toradex Easy Installer. On all modules, the Toradex Easy Installer tries to boot from SD card first using U-Boots "distroboot" scripts. As a secondary boot device, Toradex Easy Installer will boot from on-module flash, either via custom scripts (for raw NAND based devices) or using "distroboot" script on the first internal partition (for modules using eMMC).

Distroboot is a default boot script in U-Boot which searches for a script file named boot.scr or boot.scr.uimg in the root and in the folder boot of the SD card. If the script is present, it is loaded from the media and executed. The regular Toradex Easy Installer zip file contains a valid boot.scr, hence it can be unpacked and moved to the root of an SD card. For more details about distroboot refer to the documentation in doc/README.distro of the U-Boot source tree.

To change kernel boot parameter one should use the regular boot.scr file as a template.

There are some custom kernel arguments which are read by the Toradex Easy Installer:

Custom Script For Capacitive Multi-touch 7"

This is an example of a boot script which uses fdt commands to dynamically customize the device tree. In this particular example the already existing but disabled node atmel_mxt_ts is enabled by setting the status property to true. Since Toradex Easy Installer makes use of a FIT image, which contains kernel, device tree and the rootfs (squashfs), bootm start need to be used to split the booting using FIT image into two parts so that the device tree can be altered in between.

 boot.cmd
# Set timings for 7" multitouch
setenv bootargs console=ttymxc0,115200 quiet video=mxcfb0:dev=lcd,FusionF07A,if=RGB666 rootfstype=squashfs root=/dev/ram autoinstall fullscreen ${teziargs}

# Reenable fdt relocation since in place fdt edits corrupt the ramdisk
# in a FIT image...
setenv fdt_high

# Load FIT image from location as detected by distroboot
load ${devtype} ${devnum}:${bootpart} ${ramdisk_addr_r} ${prefix}tezi.itb

bootm start ${ramdisk_addr_r} && bootm loados && bootm ramdisk && bootm fdt

# Enable capacitive multitouch driver
fdt set /soc/aips-bus@02100000/i2c@021a8000/atmel_mxt_ts@4a status okay

bootm prep && bootm go

Then create a U-Boot script image:

mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "Distro boot script" -d boot.cmd boot.scr

This script placed into the root of an SD card, alongside the Toradex Easy Installer for Colibri iMX6 binaries, will make sure that the Toradex Easy Installer is properly displayed and touch-enabled when using the Capacitive Multi-touch 7" display.

Enumeration Issue during Recovery

The Toradex Easy Installer SPL/U-Boot bootloader re-enumerates as different USB devices during recovery mode. Sometimes this leads to an issue, resulting in an error message like:

Downloading Toradex Easy Installer...
Could not open device vid=0x1b67 pid=0x4fff
 
Downloading Toradex Easy Installer failed...

If you are using the Ixora Carrier Board, make sure that X9 is configured in OTG mode (remove JP2).

If the issue still persists, try a different cable, using a none-USB3 port, or connect a USB hub between your Host and the device.

Serial Console

There is a serial console available on UART1/UART_A. The main UI process is /usr/bin/tezi. A log file which contains all debug output of the UI is available in the file /var/volatile/tezi.log. To show the current content of the log file using the cat command:

cat /var/volatile/tezi.log

To kill the UI, use:

killall tezi

(note this does not clear the framebuffer, hence the last state of the UI will remain visible)

To manually restart the UI use the following command (overwriting the standard input is essential, otherwise Qt re-configures the connected tty which is fatal for the serial console):

/usr/bin/tezi -qws < /dev/null

Download Halts or Aborts

Behind some firewalls download of images might slow down or even stop with an error message:

curl: (56) Recv failure: Connection reset by peer

Some firewalls have issues with TCP window scale option. This can be disabled using

sysctl -w "net.ipv4.tcp_window_scaling=0"

Boot Arguments

The Toradex Easy Installer boot scripts start with a fixed set of Linux kernel parameters. However, it also appends any variables defined in teziargs. Since the Toradex Easy Installer builds on top of Linux, any Linux arguments can be used such as debug to get the full Kernel debug output.